2 Using RMarkdown in RStudio

The benefits of R Markdown are best appreciated when using it within RStudio (or RStudio Cloud). From RStudio, you can easily create a new R Markdown file by going to the “New File” symbol in the top left hand corner and select “R Markdown”.

The following window then asks you for a title, the author and what format you’d like the final rendered file to be. All of these elements can be changed later if you change your mind. You can also see from the left hand tab that R Markdown can be used to make other things besides documents, including presentations and shiny apps. For now, give the document an appropriate title, indicate your name, and choose “HTML” as the output format:

The new R Markdown file - which is actually a plain text file with the extension .Rmd - should now have opened on the left hand side, above the console window.

The document already has some content to serve as an example or template. It has three parts:

1. An (optional) YAML header at the top of the page, surrounded between two lines of three dashes (---). This controls the metadata (title, author, date) and the type of output format we want.
2. Chunks of R code surrounded by ```. Whene rendering, it will execute that code chunks and show the result.
3. Text mixed with formated text like **bold** and ## headers.

When opening an .Rmd file, code, text and output are interleaved. You can run each code chunk by clicking the Run icon (a play button at the top of the chunk), or by pressing Cmd/Ctrl + Shift + Enter. RStudio executes the code and displays the results inline with the code:

To produce a complete report containing all text, code, and results, click “Knit” or press Cmd/Ctrl + Shift + K. This will display the report in the viewer pane, and create a self-contained HTML file that you can share with others.

3 Adding and formatting text

Formatting text in R markdown is extremely easy. .Rmd files are meant to contain text written in markdown⧉. Markdown is a set of conventions for formatting plain text. You can use markdown to indicate:

• bold and italic text
• lists
• headers (e.g., section titles)
• hyperlinks
• images
• and much more

Plain text is written like in any other document like a word document. But you can easily format your text. For example:

• To insert a break between paragraphs, include a single completely blank line.

• To force a line break, put two blank
  spaces at the end of a line.

• Italics: Write your text within one asterisk (*Italic text*) or underscores (_Italic text_).

• Bold: Write your text within two asterisks (**Bold example**) or two underscores (__Bold example__).

• Superscripts: you must surround your text within ^ like here X^2^.

• We can also format the text to look like code like this: `code `

• Section headers can be added by putting the hash symbol # before the section title. The more symbols # you write before your text, the smaller the size of your title.

 # Title level1
 ## Title level 2
 ### Title level 3

• We can also easily create lists.Unordered lists can be created using -, *or +, and ordered lists with numbers.

# Unordered list
- Bulleted list item 1
- List item 2
    - Item 2a
    - Item 2b
- List item 3


# Ordered list
1. First item
2. Second item
3. Third item

• Hyperlinks anchored to text have the anchor in square brackets, then the link in parentheses.

# Add a link
<http://example.com>
    
# Add a link to a phrase
[linked phrase](http://example.com)

• Embedded images begin with an exclamation mark, then the caption, then either the file address of the image (in the same directory as your . Rmd document) or a URL. Here are two examples, one for an image in the directory and one for a URL.

# Add an image
![A local image](images/02-intro-rmarkdown/etsea.jpg)

![A remote image](https://upload.wikimedia.org/wikipedia/commons/b/ba/Sagrada_Familia_nave_roof_detail.jpg)

A local image

A remote image

We can see an example of all the formating:

## My favorite TV series
It is very difficult to define our favorite series, there are so many good ones! 
It may be easier if we separate into **drama** and **commedies**.

### My favorite drama TV series

1. Breaking bad
2. The West Wing
3. Northern Exposure
4. Game of Thrones

### My favorite TV commedy series

In the case of commedies, I cannot possible rank them, but *among* my favorite commedies I can cite:

- Monty Python Flying Circus
- The Office
    - The Office UK version
    - The Office US version
- Seinfeld

### Finding new series
To find new series to watch, I often check in [IMDB](https://www.imdb.com/chart/toptv/)
Based on the ratings, this may be the next series I watch:
    
![](images/02-intro-rmarkdown/got.jpg)

The result of that code would be:

4 Code chunks

A code chunk is simply an off-set piece of code by itself. It is preceded by ```{r} on a line by itself, and ended by a line which just says ``` . The code itself goes in between. Here, for instance, is some code which randomly generates 1000 numbers according a normal distribution with mean = 0 and sd = 1, and makes an histogram of the generated numbers.

```{r}
numbers <- rnorm(1000, mean = 0, sd = 1)
hist(numbers)
```

which will produce this output:

numbers <- rnorm(1000, mean = 0, sd = 1)
hist(numbers)

Notice how the code is included, nicely formatted, in the document. Second, notice how the output of the code is also automatically included in the document, belowe the code. This behavior can be changed, as we’ll see later.

4.1 Create chunks

To run code inside an R Markdown document, you need to insert a chunk. There are three ways to do so:

1. The keyboard shortcut Cmd/Ctrl + Alt + I

2. The “Insert” button icon in the editor toolbar.

3. By manually typing the chunk delimiters ```{r} to open the chunk and ```to close it.

Tip: Try to learn the keyboard shortcut. It will save you a lot of time in the long run!

No matter the way we used to create it, a code chunk will look like this:

```{r}
norm <- rnorm(100, mean = 0, sd = 1)
```

It is important to note that code within chunks behaves exactly the same as “normal” R code. That means that any object or package that is required to run the code will need to be loaded before. The same happens with dataframes, which must be loaded before being able to work with them.

The chunk has a header, and inside the curly brackets is a space where you can set up options for that code chunk. You can run an individual chunk of code at any time by placing your cursor inside the code chunk and selecting Run > Run Current Chunk. The output will be displayed immediately below the chunk.

We can also run all chunks at once. Or all the chunks above the current one. Anyway, any R code inside a chunk will be evaluated and executed when knitting the document. In case any of the chunks produces an error, R will warn us, and it won’t knit the R Markdown document.

Chunks can be given an optional name, that must be specified inside the curly brackets, and before the options, like```{r greatname}. Giving names to chunks is optinal, but it is a good practice, since the name is then used for the images (or other files) that are generated when the document is rendered. Moreover, it allows you to easily navigate to specific chunks using the drop-down code navigator in the bottom-left of the script editor:

```{r, fig.width = 4, fig.height = 3}
norm <- rnorm(100, mean = 0, sd = 1)
hist(rnorm)
```

```{r}
iris[1:5, ]
```

  Sepal.Length Sepal.Width Petal.Length Petal.Width Species
1          5.1         3.5          1.4         0.2  setosa
2          4.9         3.0          1.4         0.2  setosa
3          4.7         3.2          1.3         0.2  setosa
4          4.6         3.1          1.5         0.2  setosa
5          5.0         3.6          1.4         0.2  setosa

```{r}
knitr::kable(iris[1:5, ], 
             caption = "A knitr table. Much nicer, isn't it?"
)
```

4.5 Inline code

There is one other way to embed R code into an R Markdown document: directly into the text, with: `r. This can be very useful if you mention properties of your data in the text. For example, we can put this text

Sepals are usually much longer than petals. 
Mean sepal length is `r format(mean(iris$Sepal.Length),digits = 3)` whereas petals are 
in average `r format(mean(iris$Petal.Length),digits = 3)` cm long.

Note: I use the function formatto avoid R displaying too many decimals. Type ?format on your console if you need to know more about this function

When the report is knit, the results of these computations are inserted into the text, so this would be seen as:

EXERCISE 4:

Now that you know how to produce a complete R Markdown document, I want you to create and R Markdown report using the ‘mtcars’ dataset, that is loaded by default with R. This dataset comprises fuel consumption and 10 aspects of automobile design and performance for 32 automobiles, so it has 32 observations and 11 variables. Please type ?mtcarsin the console to know more about this dataset and the variables it contains.

5 YAML: Rendering R markdown into documents

At the top of any RMarkdown script is a YAML header section enclosed by ---. YAML stands for “yet another markup language”. By default this includes a title, author, date and the file type you want to output to. Many other options are available for different functions and formatting. Rules in the header section will alter the whole document. For example, we can use it to add a table of content or a bibliography.

One of the most important functions of the YAML section is to control for the way the document will render. By default, it indicates the output to be HTML, through the html_document command. There are a number of basic variations on that theme, generating different types of documents:

pdf_document makes a PDF with LaTeX (an open source document layout system), which you’ll need to install. RStudio will prompt you if you don’t already have it.

word_document for Microsoft Word documents (.docx).

odt_document for OpenDocument Text documents (.odt).

rtf_document for Rich Text Format (.rtf) documents.

md_document for a Markdown document. This isn’t typically useful by itself, but you might use it if, for example, your corporate CMS or lab wiki uses markdown.

Ther are also a myriad of other packages that provide templates to produce nice websites, slides, dashboards… You can learn more about them at Grolemund and Wickham’s chapter on formats in “R for data Science” https://r4ds.had.co.nz/r-markdown-formats.html

6 To know more

R Markdown is still relatively young, and is still growing rapidly. The best place to stay on top of innovations is the official R Markdown website: http://rmarkdown.rstudio.com. It includes a nice Guide to RMarkdown that includes example tutorials as projects in RStudio Cloud, and an equally nice Quick Tour.

RStudio also produces cheatsheets for most of their tools, and R Markdown is no exception. The cheatsheet provides reminder of the main functions, and can be very useful to have on hand. You can find it here or in the left bar in RStudio Cloud

Another very interesting resource is the book “R Markdown: The Definitive Guide” by R Markdown developer Yihui Xie. The book is freely available online at https://bookdown.org/yihui/rmarkdown/" (yes, you guessed right, the book itself was generated with R Markdown!)